---
title: "Client Configuration"
description: "Configure your MCP client to connect to servers"
icon: "cog"
---

The MCPClient is your gateway to connecting with MCP servers. This guide covers all configuration options for establishing connections, managing sessions, and customizing client behavior.

<Info>
**Looking for agent configuration?** If you're building AI agents that interact with MCP servers, see the [Agent Configuration](/typescript/agent/agent-configuration) guide instead.
</Info>

## Quick Start

<CodeGroup>
```typescript TypeScript
import { MCPClient } from 'mcp-use'

// Configure your MCP servers
const config = {
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest'],
            env: { DISPLAY: ':1' }
        }
    }
}

const client = new MCPClient(config)
```

```typescript TypeScript
import { MCPClient } from 'mcp-use'

// Configure your MCP servers
const config = {
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest'],
            env: { DISPLAY: ':1' }
        }
    }
}

const client = new MCPClient(config)
```
</CodeGroup>


## Server Configuration

The MCPClient uses a flexible configuration system that supports any MCP server, regardless of connection type.

<Tip>
**Looking for MCP servers?** Check out these curated lists:
- [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- [appcypher/awesome-mcp-servers](https://github.com/appcypher/awesome-mcp-servers)
</Tip>

### Configuration Structure

Server configuration is defined as a JavaScript object:

```json
{
  "mcpServers": {
    "server_name": {
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}
```

### Configuration Parameters

Each server entry requires a unique name and connection-specific parameters. The client automatically detects the connection type based on the provided configuration.

**Common Parameters:**
- `server_name`: Unique identifier for the server (used as the object key)

**STDIO Servers (Local Process):**

For servers that run as local child processes:

- `command`: Executable command to start the server (e.g., `"npx"`, `"python"`)
- `args`: Array of command-line arguments
- `env`: Environment variables for the server process

**HTTP/HTTPS Servers (Remote):**

For servers accessible via HTTP endpoints:

- `url`: Full URL to the MCP server endpoint
- `headers`: Custom HTTP headers (useful for authentication)

<Info>
The client automatically infers the connection type based on your configuration. Use `command` for STDIO servers or `url` for HTTP servers. See [Connection Types](./connection-types) for detailed information.
</Info>

### Example Configuration

Here's a basic example of how to configure an MCP server:

```json
{
  "mcpServers": {
    "my_server": {
      "command": "npx",
      "args": ["@my-mcp/server"],
      "env": {
        "PORT": "3000"
      }
    }
  }
}
```

### Multiple Server Configuration

You can configure multiple MCP servers in a single configuration file, allowing you to use different servers for different tasks or combine their capabilities (e.g.):

```json
{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": { "DISPLAY": ":1" }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/home/pietro/projects/mcp-use/"
      ]
    }
  }
}
```

For a complete example of using multiple servers, see the [multi-server example](https://github.com/mcp-use/mcp-use/blob/main/examples/multi_server_example.py) in our repository.


## Client Creation Methods

There are several ways to create an MCPClient:

### From Dictionary/Object

Create configuration programmatically:

```typescript TypeScript
import { MCPClient } from 'mcp-use'

const config = {
    mcpServers: {
        playwright: {
            command: 'npx',
            args: ['@playwright/mcp@latest'],
            env: { DISPLAY: ':1' }
        }
    }
}

const client = new MCPClient(config)
```

### From Configuration File

Load configuration from a JSON file:

<CodeGroup>
```typescript TypeScript
import { MCPClient, loadConfigFile } from 'mcp-use'

const config = await loadConfigFile('config.json')
const client = new MCPClient(config)
```

```typescript TypeScript
import { MCPClient, loadConfigFile } from 'mcp-use'

const config = await loadConfigFile('config.json')
const client = new MCPClient(config)
```
</CodeGroup>


### With Sandbox Options

Enable sandboxed execution:

<CodeGroup>
```typescript TypeScript
// Note: Sandbox mode is not yet supported in the TypeScript library
// This is a planned feature for a future release
```

```typescript TypeScript
// Note: Sandbox mode is not yet supported in the TypeScript library
// This is a planned feature for a future release
```
</CodeGroup>

## Best Practices

1. **API Keys**: Always use environment variables for sensitive information
2. **Configuration Files**: Keep configuration files in version control (without sensitive data)
3. **Server Naming**: Use descriptive names for your MCP servers
4. **Environment Variables**: Set appropriate environment variables for each server
5. **Testing**: Test server connections independently before using with agents
6. **Monitoring**: Enable logging to monitor server connection health

## Error Handling

Common client configuration errors and solutions:

1. **Server Not Found**: Check if the server command is installed and accessible
2. **Connection Timeout**: Verify server is running and network connectivity
3. **Permission Denied**: Ensure proper file permissions and environment setup
4. **Invalid Configuration**: Validate JSON syntax and required fields

For detailed information, see the [Connection Types](./connection-types) guide.
